"""
GomerX 摄像头模块
用于获取和处理机器人摄像头的图像数据
"""

# 导入必要的系统模块
import cv2  # OpenCV库，用于图像处理和摄像头操作
import numpy as np  # NumPy库，用于数值计算和数组操作
from config.settings import CAMERA_CONFIG  # 导入摄像头配置参数

class Camera:
    """GomerX 摄像头控制类
    
    负责摄像头的初始化、打开、关闭、图像读取和保存等操作
    """
    
    def __init__(self, camera_id=0):
        """
        初始化摄像头
        
        Args:
            camera_id: 摄像头ID，默认为0，通常表示系统默认摄像头
        """
        # 保存摄像头ID，用于指定使用哪个摄像头
        self.camera_id = camera_id
        
        # 初始化摄像头对象，初始为None
        self.cap = None
        
        # 从配置文件加载摄像头参数
        self.resolution = CAMERA_CONFIG["resolution"]  # 图像分辨率 [宽度, 高度]
        self.fps = CAMERA_CONFIG["fps"]  # 帧率（每秒帧数）
        
        # 摄像头打开状态，初始为未打开
        self.is_opened = False
        
    def open(self):
        """打开摄像头
        
        初始化摄像头设备并设置参数
        
        Returns:
            bool: 打开是否成功
        """
        try:
            # 创建VideoCapture对象，用于捕获摄像头视频流
            self.cap = cv2.VideoCapture(self.camera_id)
            
            # 检查摄像头是否成功打开
            if not self.cap.isOpened():
                raise Exception(f"无法打开摄像头 {self.camera_id}")
                
            # 设置图像分辨率
            # CAP_PROP_FRAME_WIDTH: 设置图像宽度
            self.cap.set(cv2.CAP_PROP_FRAME_WIDTH, self.resolution[0])
            # CAP_PROP_FRAME_HEIGHT: 设置图像高度
            self.cap.set(cv2.CAP_PROP_FRAME_HEIGHT, self.resolution[1])
            
            # 设置帧率（每秒帧数）
            self.cap.set(cv2.CAP_PROP_FPS, self.fps)
            
            # 更新摄像头状态为已打开
            self.is_opened = True
            return True  # 返回成功
            
        except Exception as e:
            # 捕获打开过程中的异常
            print(f"打开摄像头失败: {e}")  # 输出错误信息
            return False  # 返回失败
    
    def close(self):
        """关闭摄像头
        
        释放摄像头资源，以便其他程序可以使用
        """
        # 检查摄像头对象是否存在且已打开
        if self.cap and self.is_opened:
            # 释放摄像头资源
            self.cap.release()
            # 更新状态为未打开
            self.is_opened = False
    
    def read_frame(self):
        """
        读取一帧图像
        
        从摄像头获取当前帧的图像数据
        
        Returns:
            numpy.ndarray: 图像数据，如果读取失败返回None
        """
        # 检查摄像头是否已打开
        if not self.is_opened or not self.cap:
            print("摄像头未打开")  # 输出错误信息
            return None  # 返回None表示失败
            
        # 从摄像头读取一帧图像
        # ret: 布尔值，表示是否成功读取帧
        # frame: 图像数据，如果读取失败则为None
        ret, frame = self.cap.read()
        
        # 检查是否成功读取帧
        if not ret:
            print("无法读取摄像头帧")  # 输出错误信息
            return None  # 返回None表示失败
            
        # 返回图像数据
        return frame
    
    def save_frame(self, frame, filename):
        """
        保存图像帧到文件
        
        将图像数据保存为指定文件名的图像文件
        
        Args:
            frame: 图像数据（numpy数组）
            filename: 保存的文件名，可以包含路径
            
        Returns:
            bool: 保存是否成功
        """
        try:
            # 使用OpenCV的imwrite函数保存图像
            cv2.imwrite(filename, frame)
            return True  # 返回成功
        except Exception as e:
            # 捕获保存过程中的异常
            print(f"保存图像失败: {e}")  # 输出错误信息
            return False  # 返回失败
    
    def __del__(self):
        """析构函数，确保摄像头被关闭
        
        当对象被销毁时自动调用，确保摄像头资源被正确释放
        """
        self.close()  # 调用close方法关闭摄像头